dotenvdrift 0.1.0__tar.gz

dotenvdrift-0.1.0/LICENSE

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

dotenvdrift-0.1.0/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: dotenvdrift
+Version: 0.1.0
+Summary: Repo-local CLI for env drift across code, .env.example, Docker, and GitHub Actions.
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/KevinHansen90/dotenvdrift
+Project-URL: Repository, https://github.com/KevinHansen90/dotenvdrift
+Project-URL: Issues, https://github.com/KevinHansen90/dotenvdrift/issues
+Keywords: dotenv,env,env-drift,config-drift,cli,github-actions,docker,repo-local
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/KevinHansen90/dotenvdrift/main/docs/assets/dotenvdrift-logo.png" alt="dotenvdrift logo" width="720">
+</p>
+
+<h1 align="center">dotenvdrift</h1>
+
+<p align="center">
+  <a href="https://www.python.org/downloads/">
+    <img src="https://img.shields.io/badge/python-3.11%2B-3776AB?logo=python&logoColor=white" alt="Python 3.11+">
+  </a>
+  <a href="LICENSE">
+    <img src="https://img.shields.io/badge/license-MIT-2ea44f" alt="MIT License">
+  </a>
+</p>
+
+<p align="center">
+  Small repo-local CLI that catches env drift between code, <code>.env.example</code>, Docker / docker-compose, and GitHub Actions.
+</p>
+
+## Why
+
+I built this after repeatedly hitting env drift while moving quickly, including with coding agents: the code was done, but `.env.example`, Docker, docker-compose, and GitHub Actions had drifted apart.
+
+That failure mode is not specific to AI-assisted repos. It breaks onboarding, local runs, and CI in any repo. This tool is just especially handy in fast-moving codebases where config drift shows up early.
+
+## What It Checks
+
+- `missing`: used in code but absent from `.env.example`
+- `undocumented`: referenced in Docker or GitHub Actions but not documented locally
+- `unused`: still listed in `.env.example` but no longer referenced
+
+It scans Python and JS/TS code, `.env.example`, Docker / docker-compose files, and GitHub Actions workflows with simple deterministic patterns.
+
+## Install
+
+Requires Python 3.11+.
+
+```bash
+uv sync
+```
+
+Fallback:
+
+```bash
+python -m pip install .
+```
+
+## Usage
+
+```bash
+uv run dotenvdrift .
+uv run dotenvdrift examples/broken-repo
+uv run dotenvdrift . --json
+uv run dotenvdrift . --strict
+uv run dotenvdrift . --only missing
+```
+
+Sample output:
+
+```text
+missing
+  NODE_ENV             web/client.ts:2
+  OPENAI_API_KEY       app/settings.py:4
+  VITE_API_BASE_URL    web/client.ts:1
+
+undocumented
+  DATABASE_URL         docker-compose.yml:5
+  PYPI_TOKEN           .github/workflows/release.yml:11
+  RELEASE_REGION       .github/workflows/release.yml:7
+
+unused
+  DEBUG_SQL            .env.example:2
+
+✗ 7 drift issues
+```
+
+## Limits
+
+- It never loads or prints env values, only names and locations.
+- It uses line-based regex scans, not ASTs or YAML parsers.
+- It stays generic. AWS, GCP, Azure, and crypto repos work when they use env vars, but there is no provider-specific logic.
+- It does not sync secrets, manage vaults, validate schemas, or auto-fix anything.
+
+## Development
+
+```bash
+uv run python -m unittest discover -s tests -p 'test_*.py' -v
+uv build
+```
+
+## Exit Codes
+
+- `0`: no issues, or issues found without `--strict`
+- `1`: issues found with `--strict`
+- `2`: invalid repository path
+
+## License
+
+MIT

dotenvdrift-0.1.0/README.md

@@ -0,0 +1,99 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/KevinHansen90/dotenvdrift/main/docs/assets/dotenvdrift-logo.png" alt="dotenvdrift logo" width="720">
+</p>
+
+<h1 align="center">dotenvdrift</h1>
+
+<p align="center">
+  <a href="https://www.python.org/downloads/">
+    <img src="https://img.shields.io/badge/python-3.11%2B-3776AB?logo=python&logoColor=white" alt="Python 3.11+">
+  </a>
+  <a href="LICENSE">
+    <img src="https://img.shields.io/badge/license-MIT-2ea44f" alt="MIT License">
+  </a>
+</p>
+
+<p align="center">
+  Small repo-local CLI that catches env drift between code, <code>.env.example</code>, Docker / docker-compose, and GitHub Actions.
+</p>
+
+## Why
+
+I built this after repeatedly hitting env drift while moving quickly, including with coding agents: the code was done, but `.env.example`, Docker, docker-compose, and GitHub Actions had drifted apart.
+
+That failure mode is not specific to AI-assisted repos. It breaks onboarding, local runs, and CI in any repo. This tool is just especially handy in fast-moving codebases where config drift shows up early.
+
+## What It Checks
+
+- `missing`: used in code but absent from `.env.example`
+- `undocumented`: referenced in Docker or GitHub Actions but not documented locally
+- `unused`: still listed in `.env.example` but no longer referenced
+
+It scans Python and JS/TS code, `.env.example`, Docker / docker-compose files, and GitHub Actions workflows with simple deterministic patterns.
+
+## Install
+
+Requires Python 3.11+.
+
+```bash
+uv sync
+```
+
+Fallback:
+
+```bash
+python -m pip install .
+```
+
+## Usage
+
+```bash
+uv run dotenvdrift .
+uv run dotenvdrift examples/broken-repo
+uv run dotenvdrift . --json
+uv run dotenvdrift . --strict
+uv run dotenvdrift . --only missing
+```
+
+Sample output:
+
+```text
+missing
+  NODE_ENV             web/client.ts:2
+  OPENAI_API_KEY       app/settings.py:4
+  VITE_API_BASE_URL    web/client.ts:1
+
+undocumented
+  DATABASE_URL         docker-compose.yml:5
+  PYPI_TOKEN           .github/workflows/release.yml:11
+  RELEASE_REGION       .github/workflows/release.yml:7
+
+unused
+  DEBUG_SQL            .env.example:2
+
+✗ 7 drift issues
+```
+
+## Limits
+
+- It never loads or prints env values, only names and locations.
+- It uses line-based regex scans, not ASTs or YAML parsers.
+- It stays generic. AWS, GCP, Azure, and crypto repos work when they use env vars, but there is no provider-specific logic.
+- It does not sync secrets, manage vaults, validate schemas, or auto-fix anything.
+
+## Development
+
+```bash
+uv run python -m unittest discover -s tests -p 'test_*.py' -v
+uv build
+```
+
+## Exit Codes
+
+- `0`: no issues, or issues found without `--strict`
+- `1`: issues found with `--strict`
+- `2`: invalid repository path
+
+## License
+
+MIT

dotenvdrift-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=77.0.3"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "dotenvdrift"
+version = "0.1.0"
+description = "Repo-local CLI for env drift across code, .env.example, Docker, and GitHub Actions."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["dotenv", "env", "env-drift", "config-drift", "cli", "github-actions", "docker", "repo-local"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Quality Assurance",
+  "Topic :: Software Development :: Build Tools",
+]
+
+[project.scripts]
+dotenvdrift = "dotenvdrift.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/KevinHansen90/dotenvdrift"
+Repository = "https://github.com/KevinHansen90/dotenvdrift"
+Issues = "https://github.com/KevinHansen90/dotenvdrift/issues"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

dotenvdrift-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

dotenvdrift-0.1.0/src/dotenvdrift/__init__.py

@@ -0,0 +1,3 @@
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

dotenvdrift-0.1.0/src/dotenvdrift/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

dotenvdrift-0.1.0/src/dotenvdrift/cli.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from dataclasses import asdict
+
+from .__init__ import __version__
+from .core import AuditResult, audit, select_issues
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="dotenvdrift",
+        description="Catch env var drift between code, .env.example, Docker, and GitHub Actions.",
+    )
+    parser.add_argument("path", nargs="?", default=".", help="Repository path")
+    parser.add_argument("--json", action="store_true", help="Print machine-readable output")
+    parser.add_argument("--strict", action="store_true", help="Exit non-zero when any issue is found")
+    parser.add_argument(
+        "--only",
+        choices=("missing", "undocumented", "unused"),
+        help="Show a single issue group",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        result = audit(args.path)
+    except (FileNotFoundError, NotADirectoryError) as error:
+        print(f"error: {error}", file=sys.stderr)
+        return 2
+    if args.json:
+        print(render_json(result, args.only))
+    else:
+        print(render_text(result, args.only))
+    total = sum(len(items) for _, items in select_issues(result, args.only))
+    return 1 if args.strict and total else 0
+
+
+def render_json(result: AuditResult, only: str | None) -> str:
+    payload = {
+        "root": result.root,
+        "documented_files": result.documented_files,
+        "counts": result.counts(only),
+        "issues": {
+            name: [asdict(issue) for issue in issues]
+            for name, issues in select_issues(result, only)
+        },
+    }
+    return json.dumps(payload, indent=2, sort_keys=True)
+
+
+def render_text(result: AuditResult, only: str | None) -> str:
+    groups = select_issues(result, only)
+    total = sum(len(items) for _, items in groups)
+    if total == 0:
+        return "✓ no env drift found"
+
+    lines: list[str] = []
+    for name, issues in groups:
+        if not issues:
+            continue
+        lines.append(name)
+        for issue in issues:
+            label = issue.name.ljust(20)
+            if issue.first_seen:
+                lines.append(f"  {label} {issue.first_seen}")
+            else:
+                lines.append(f"  {label}")
+        lines.append("")
+    lines.append(f"✗ {total} drift issue{'s' if total != 1 else ''}")
+    return "\n".join(lines).rstrip()

dotenvdrift-0.1.0/src/dotenvdrift/core.py

@@ -0,0 +1,260 @@
+from __future__ import annotations
+
+import os
+from collections import defaultdict
+from collections.abc import Iterator
+from dataclasses import dataclass
+from pathlib import Path
+import re
+
+IGNORE_DIRS = {".git", "node_modules", ".venv", "venv", "dist", "build", "__pycache__"}
+CODE_EXTENSIONS = {".py", ".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs"}
+YAML_EXTENSIONS = {".yml", ".yaml"}
+MAX_FILE_BYTES = 1_000_000
+VAR_RE = r"[A-Z][A-Z0-9_]*"
+
+PYTHON_PATTERNS = (
+    re.compile(rf"os\.getenv\(\s*[\"']({VAR_RE})[\"']"),
+    re.compile(rf"os\.environ\.get\(\s*[\"']({VAR_RE})[\"']"),
+    re.compile(rf"os\.environ\[\s*[\"']({VAR_RE})[\"']\s*\]"),
+)
+JS_PATTERNS = (
+    re.compile(rf"process\.env\.({VAR_RE})\b"),
+    re.compile(rf"process\.env\[\s*[\"']({VAR_RE})[\"']\s*\]"),
+    re.compile(rf"import\.meta\.env\.({VAR_RE})\b"),
+)
+ACTIONS_INLINE_PATTERNS = (
+    re.compile(rf"\$\{{\{{\s*secrets\.({VAR_RE})\s*\}}\}}"),
+    re.compile(rf"\$\{{\{{\s*vars\.({VAR_RE})\s*\}}\}}"),
+)
+DOCKER_SUBSTITUTION = re.compile(rf"\$\{{({VAR_RE})(?::-[^}}]*)?\}}")
+ENV_KEY_LINE = re.compile(rf"^({VAR_RE})\s*:")
+ENV_FILE_KEY = re.compile(rf"^(?:export\s+)?({VAR_RE})\s*=")
+
+
+@dataclass(frozen=True, slots=True)
+class Hit:
+    source: str
+    path: str
+    line: int
+
+
+@dataclass(frozen=True, slots=True)
+class Issue:
+    kind: str
+    name: str
+    first_seen: str | None
+
+
+@dataclass(slots=True)
+class AuditResult:
+    root: str
+    documented_files: list[str]
+    missing: list[Issue]
+    undocumented: list[Issue]
+    unused: list[Issue]
+
+    def counts(self, only: str | None = None) -> dict[str, int]:
+        counts = {"missing": 0, "undocumented": 0, "unused": 0}
+        for name, issues in select_issues(self, only):
+            counts[name] = len(issues)
+        counts["total"] = counts["missing"] + counts["undocumented"] + counts["unused"]
+        return counts
+
+
+class ReferenceIndex:
+    def __init__(self) -> None:
+        self._hits: dict[str, list[Hit]] = defaultdict(list)
+
+    def add(self, name: str, source: str, path: Path, line: int) -> None:
+        hit = Hit(source=source, path=path.as_posix(), line=line)
+        if hit not in self._hits[name]:
+            self._hits[name].append(hit)
+
+    def names(self) -> set[str]:
+        return set(self._hits)
+
+    def hits_for(self, name: str) -> list[Hit]:
+        return self._hits.get(name, [])
+
+    def first_seen(self, name: str) -> str | None:
+        hits = self.hits_for(name)
+        if not hits:
+            return None
+        first = sorted(hits, key=lambda item: (item.path, item.line))[0]
+        return f"{first.path}:{first.line}"
+
+    def has_source(self, name: str, source: str) -> bool:
+        return any(hit.source == source for hit in self.hits_for(name))
+
+
+def audit(root: str | Path) -> AuditResult:
+    base = resolve_root(root)
+    documented, documented_files, documented_locations = read_documented_keys(base)
+    refs = collect_references(base)
+
+    missing_names = sorted(
+        name for name in refs.names() if name not in documented and refs.has_source(name, "code")
+    )
+    undocumented_names = sorted(
+        name
+        for name in refs.names()
+        if name not in documented
+        and not refs.has_source(name, "code")
+        and (refs.has_source(name, "actions") or refs.has_source(name, "docker"))
+    )
+    unused_names = sorted(name for name in documented if name not in refs.names())
+
+    return AuditResult(
+        root=base.as_posix(),
+        documented_files=documented_files,
+        missing=[Issue("missing", name, refs.first_seen(name)) for name in missing_names],
+        undocumented=[Issue("undocumented", name, refs.first_seen(name)) for name in undocumented_names],
+        unused=[Issue("unused", name, documented_locations.get(name)) for name in unused_names],
+    )
+
+
+def resolve_root(root: str | Path) -> Path:
+    base = Path(root).expanduser().resolve()
+    if not base.exists():
+        raise FileNotFoundError(f"repository path not found: {base}")
+    if not base.is_dir():
+        raise NotADirectoryError(f"repository path is not a directory: {base}")
+    return base
+
+
+def read_documented_keys(root: Path) -> tuple[set[str], list[str], dict[str, str]]:
+    files: list[str] = []
+    keys: set[str] = set()
+    locations: dict[str, str] = {}
+    for path in walk_files(root):
+        if path.name != ".env.example":
+            continue
+        relative = path.relative_to(root).as_posix()
+        files.append(relative)
+        for line_number, raw_line in enumerate(read_text(path).splitlines(), start=1):
+            line = raw_line.strip()
+            if not line or line.startswith("#"):
+                continue
+            match = ENV_FILE_KEY.match(line)
+            if match:
+                name = match.group(1)
+                keys.add(name)
+                locations.setdefault(name, f"{relative}:{line_number}")
+    return keys, sorted(files), locations
+
+
+def collect_references(root: Path) -> ReferenceIndex:
+    refs = ReferenceIndex()
+    for path in walk_files(root):
+        if is_oversized(path):
+            continue
+        suffix = path.suffix.lower()
+        text = read_text(path)
+        rel_path = path.relative_to(root)
+        if suffix in CODE_EXTENSIONS:
+            if suffix == ".py":
+                scan_patterns(text, rel_path, PYTHON_PATTERNS, refs, "code")
+            else:
+                scan_patterns(text, rel_path, JS_PATTERNS, refs, "code")
+            continue
+        if suffix in YAML_EXTENSIONS:
+            if is_actions_file(rel_path):
+                scan_actions(text, rel_path, refs)
+            elif is_compose_file(rel_path):
+                scan_compose(text, rel_path, refs)
+    return refs
+
+
+def scan_patterns(text: str, path: Path, patterns: tuple[re.Pattern[str], ...], refs: ReferenceIndex, source: str) -> None:
+    for line_number, line in enumerate(text.splitlines(), start=1):
+        for pattern in patterns:
+            for match in pattern.finditer(line):
+                refs.add(match.group(1), source, path, line_number)
+
+
+def scan_actions(text: str, path: Path, refs: ReferenceIndex) -> None:
+    for line_number, line in enumerate(text.splitlines(), start=1):
+        for pattern in ACTIONS_INLINE_PATTERNS:
+            for match in pattern.finditer(line):
+                refs.add(match.group(1), "actions", path, line_number)
+    scan_yaml_block_keys(text, path, refs, block_name="env", source="actions")
+
+
+def scan_compose(text: str, path: Path, refs: ReferenceIndex) -> None:
+    for line_number, line in enumerate(text.splitlines(), start=1):
+        for match in DOCKER_SUBSTITUTION.finditer(line):
+            refs.add(match.group(1), "docker", path, line_number)
+    scan_yaml_block_keys(text, path, refs, block_name="environment", source="docker")
+
+
+def scan_yaml_block_keys(text: str, path: Path, refs: ReferenceIndex, *, block_name: str, source: str) -> None:
+    active_indent: int | None = None
+    for line_number, raw_line in enumerate(text.splitlines(), start=1):
+        line = raw_line.rstrip()
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+        indent = len(line) - len(line.lstrip())
+        if active_indent is not None and indent <= active_indent:
+            active_indent = None
+        if stripped == f"{block_name}:" or stripped.startswith(f"{block_name}: #"):
+            active_indent = indent
+            continue
+        if active_indent is None:
+            continue
+        match = ENV_KEY_LINE.match(stripped)
+        if match:
+            refs.add(match.group(1), source, path, line_number)
+            continue
+        if stripped.startswith("- "):
+            list_match = re.match(rf"-\s*({VAR_RE})=", stripped)
+            if list_match:
+                refs.add(list_match.group(1), source, path, line_number)
+
+
+def walk_files(root: Path) -> Iterator[Path]:
+    for current_root, dirnames, filenames in os.walk(root):
+        dirnames[:] = sorted(name for name in dirnames if name not in IGNORE_DIRS)
+        for filename in sorted(filenames):
+            yield Path(current_root, filename)
+
+
+def is_oversized(path: Path) -> bool:
+    try:
+        return path.stat().st_size > MAX_FILE_BYTES
+    except OSError:
+        return True
+
+
+def read_text(path: Path) -> str:
+    try:
+        return path.read_text(encoding="utf-8")
+    except UnicodeDecodeError:
+        try:
+            return path.read_text(encoding="utf-8", errors="ignore")
+        except OSError:
+            return ""
+    except OSError:
+        return ""
+
+
+def is_actions_file(path: Path) -> bool:
+    parts = path.parts
+    return len(parts) >= 3 and parts[0] == ".github" and parts[1] == "workflows"
+
+
+def is_compose_file(path: Path) -> bool:
+    name = path.name.lower()
+    return name in {"docker-compose.yml", "docker-compose.yaml", "compose.yml", "compose.yaml"}
+
+
+def select_issues(result: AuditResult, only: str | None = None) -> list[tuple[str, list[Issue]]]:
+    groups = [
+        ("missing", result.missing),
+        ("undocumented", result.undocumented),
+        ("unused", result.unused),
+    ]
+    if only is None:
+        return groups
+    return [group for group in groups if group[0] == only]

dotenvdrift-0.1.0/src/dotenvdrift.egg-info/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: dotenvdrift
+Version: 0.1.0
+Summary: Repo-local CLI for env drift across code, .env.example, Docker, and GitHub Actions.
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/KevinHansen90/dotenvdrift
+Project-URL: Repository, https://github.com/KevinHansen90/dotenvdrift
+Project-URL: Issues, https://github.com/KevinHansen90/dotenvdrift/issues
+Keywords: dotenv,env,env-drift,config-drift,cli,github-actions,docker,repo-local
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/KevinHansen90/dotenvdrift/main/docs/assets/dotenvdrift-logo.png" alt="dotenvdrift logo" width="720">
+</p>
+
+<h1 align="center">dotenvdrift</h1>
+
+<p align="center">
+  <a href="https://www.python.org/downloads/">
+    <img src="https://img.shields.io/badge/python-3.11%2B-3776AB?logo=python&logoColor=white" alt="Python 3.11+">
+  </a>
+  <a href="LICENSE">
+    <img src="https://img.shields.io/badge/license-MIT-2ea44f" alt="MIT License">
+  </a>
+</p>
+
+<p align="center">
+  Small repo-local CLI that catches env drift between code, <code>.env.example</code>, Docker / docker-compose, and GitHub Actions.
+</p>
+
+## Why
+
+I built this after repeatedly hitting env drift while moving quickly, including with coding agents: the code was done, but `.env.example`, Docker, docker-compose, and GitHub Actions had drifted apart.
+
+That failure mode is not specific to AI-assisted repos. It breaks onboarding, local runs, and CI in any repo. This tool is just especially handy in fast-moving codebases where config drift shows up early.
+
+## What It Checks
+
+- `missing`: used in code but absent from `.env.example`
+- `undocumented`: referenced in Docker or GitHub Actions but not documented locally
+- `unused`: still listed in `.env.example` but no longer referenced
+
+It scans Python and JS/TS code, `.env.example`, Docker / docker-compose files, and GitHub Actions workflows with simple deterministic patterns.
+
+## Install
+
+Requires Python 3.11+.
+
+```bash
+uv sync
+```
+
+Fallback:
+
+```bash
+python -m pip install .
+```
+
+## Usage
+
+```bash
+uv run dotenvdrift .
+uv run dotenvdrift examples/broken-repo
+uv run dotenvdrift . --json
+uv run dotenvdrift . --strict
+uv run dotenvdrift . --only missing
+```
+
+Sample output:
+
+```text
+missing
+  NODE_ENV             web/client.ts:2
+  OPENAI_API_KEY       app/settings.py:4
+  VITE_API_BASE_URL    web/client.ts:1
+
+undocumented
+  DATABASE_URL         docker-compose.yml:5
+  PYPI_TOKEN           .github/workflows/release.yml:11
+  RELEASE_REGION       .github/workflows/release.yml:7
+
+unused
+  DEBUG_SQL            .env.example:2
+
+✗ 7 drift issues
+```
+
+## Limits
+
+- It never loads or prints env values, only names and locations.
+- It uses line-based regex scans, not ASTs or YAML parsers.
+- It stays generic. AWS, GCP, Azure, and crypto repos work when they use env vars, but there is no provider-specific logic.
+- It does not sync secrets, manage vaults, validate schemas, or auto-fix anything.
+
+## Development
+
+```bash
+uv run python -m unittest discover -s tests -p 'test_*.py' -v
+uv build
+```
+
+## Exit Codes
+
+- `0`: no issues, or issues found without `--strict`
+- `1`: issues found with `--strict`
+- `2`: invalid repository path
+
+## License
+
+MIT

dotenvdrift-0.1.0/src/dotenvdrift.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+src/dotenvdrift/__init__.py
+src/dotenvdrift/__main__.py
+src/dotenvdrift/cli.py
+src/dotenvdrift/core.py
+src/dotenvdrift.egg-info/PKG-INFO
+src/dotenvdrift.egg-info/SOURCES.txt
+src/dotenvdrift.egg-info/dependency_links.txt
+src/dotenvdrift.egg-info/entry_points.txt
+src/dotenvdrift.egg-info/top_level.txt
+tests/test_dotenvdrift.py

dotenvdrift-0.1.0/src/dotenvdrift.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

dotenvdrift-0.1.0/src/dotenvdrift.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+dotenvdrift = dotenvdrift.cli:main

dotenvdrift-0.1.0/src/dotenvdrift.egg-info/top_level.txt

@@ -0,0 +1 @@
+dotenvdrift

dotenvdrift-0.1.0/tests/test_dotenvdrift.py

@@ -0,0 +1,134 @@
+from __future__ import annotations
+
+import contextlib
+import io
+import json
+import tempfile
+import unittest
+from pathlib import Path
+
+from dotenvdrift.cli import main, render_json
+from dotenvdrift.core import audit
+
+
+def write(root: Path, relative_path: str, text: str) -> None:
+    path = root / relative_path
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(text, encoding="utf-8")
+
+
+class AuditTests(unittest.TestCase):
+    def run_cli(self, argv: list[str]) -> tuple[int, str, str]:
+        stdout = io.StringIO()
+        stderr = io.StringIO()
+        with contextlib.redirect_stdout(stdout), contextlib.redirect_stderr(stderr):
+            code = main(argv)
+        return code, stdout.getvalue(), stderr.getvalue()
+
+    def test_reports_missing_undocumented_and_unused(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            write(root, ".env.example", "APP_ENV=dev\nDEBUG_SQL=false\nSHARED_KEY=1\n")
+            write(
+                root,
+                "app.py",
+                "import os\nOPENAI_API_KEY = os.getenv('OPENAI_API_KEY')\nSHARED_KEY = os.environ['SHARED_KEY']\n",
+            )
+            write(
+                root,
+                ".github/workflows/release.yml",
+                "name: release\n"
+                "on: push\n"
+                "jobs:\n"
+                "  ship:\n"
+                "    runs-on: ubuntu-latest\n"
+                "    env:\n"
+                "      RELEASE_REGION: us-east-1\n"
+                "    steps:\n"
+                "      - run: echo ${{ secrets.PYPI_TOKEN }}\n",
+            )
+            write(
+                root,
+                "docker-compose.yml",
+                "services:\n"
+                "  api:\n"
+                "    environment:\n"
+                "      DATABASE_URL: ${DATABASE_URL}\n",
+            )
+
+            result = audit(root)
+
+            self.assertEqual([issue.name for issue in result.missing], ["OPENAI_API_KEY"])
+            self.assertEqual(
+                [issue.name for issue in result.undocumented],
+                ["DATABASE_URL", "PYPI_TOKEN", "RELEASE_REGION"],
+            )
+            self.assertEqual([issue.name for issue in result.unused], ["APP_ENV", "DEBUG_SQL"])
+
+    def test_json_output_shape(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            write(root, ".env.example", "APP_ENV=dev\n")
+            payload = json.loads(render_json(audit(root), None))
+            self.assertEqual(payload["counts"]["total"], 1)
+            self.assertIn("unused", payload["issues"])
+
+    def test_json_only_filters_counts(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            write(root, ".env.example", "APP_ENV=dev\n")
+            write(root, "app.py", "import os\nos.getenv('OPENAI_API_KEY')\n")
+
+            payload = json.loads(render_json(audit(root), "missing"))
+
+            self.assertEqual(
+                payload["counts"],
+                {"missing": 1, "undocumented": 0, "unused": 0, "total": 1},
+            )
+            self.assertEqual(sorted(payload["issues"]), ["missing"])
+
+    def test_strict_exit_code(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            write(root, ".env.example", "APP_ENV=dev\n")
+
+            code, _, _ = self.run_cli([str(root), "--strict"])
+
+            self.assertEqual(code, 1)
+
+    def test_missing_path_returns_error(self) -> None:
+        code, _, stderr = self.run_cli(["/tmp/dotenvdrift-missing-path"])
+
+        self.assertEqual(code, 2)
+        self.assertIn("repository path not found", stderr)
+
+    def test_ignores_node_modules(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            write(root, "node_modules/pkg/.env.example", "IGNORED=1\n")
+            write(root, "app/app.py", "import os\nos.getenv('LIVE_KEY')\n")
+
+            result = audit(root)
+
+            self.assertEqual([issue.name for issue in result.missing], ["LIVE_KEY"])
+            self.assertEqual(result.unused, [])
+
+    def test_compose_environment_list_entries_are_scanned(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            write(
+                root,
+                "docker-compose.yml",
+                "services:\n"
+                "  api:\n"
+                "    environment:\n"
+                "      - DATABASE_URL=${DATABASE_URL}\n",
+            )
+
+            result = audit(root)
+
+            self.assertEqual([issue.name for issue in result.undocumented], ["DATABASE_URL"])
+
+
+if __name__ == "__main__":
+    unittest.main()