dotenvdrift 0.1.0__py3-none-any.whl

dotenvdrift/__init__.py

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

dotenvdrift/__main__.py

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

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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,10 @@
+dotenvdrift/__init__.py,sha256=4t_crzhrLum--oyowUMxtjBTzUtWp7oRTF22ewEvJG4,49
+dotenvdrift/__main__.py,sha256=MHKZ_ae3fSLGTLUUMOx15fWdeOnJSHhq-zslRP5F5Lc,79
+dotenvdrift/cli.py,sha256=bSdz-5-T1NucIuZOeyN7T-uGj-2Poi6wYfyLhY_SYn0,2565
+dotenvdrift/core.py,sha256=LUx4PsJJQGPFG4oc765doXppoCeoDFVl1M3qahVuoz4,9184
+dotenvdrift-0.1.0.dist-info/licenses/LICENSE,sha256=v2spsd7N1pKFFh2G8wGP_45iwe5S0DYiJzG4im8Rupc,1066
+dotenvdrift-0.1.0.dist-info/METADATA,sha256=ra6PnQXwJQkRFJRmgPBl-X_CgpIVfYzQQAwq7hhnZpA,3746
+dotenvdrift-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+dotenvdrift-0.1.0.dist-info/entry_points.txt,sha256=gDSg_tGTq5K12zA-FkfkdeyKDtxTlQ8YJB4bG1uVhOw,53
+dotenvdrift-0.1.0.dist-info/top_level.txt,sha256=OKMLFvjVQY2JO-y6xpUTJC7MUp-YV37eMtx8dS8BB2Q,12
+dotenvdrift-0.1.0.dist-info/RECORD,,

dotenvdrift-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

dotenvdrift-0.1.0.dist-info/entry_points.txt

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

dotenvdrift-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

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