env-example-sync-cli 0.1.0__py3-none-any.whl

env_example_sync.py

@@ -0,0 +1,214 @@
+#!/usr/bin/env python3
+"""Keep .env.example in sync with the environment variables code actually uses.
+
+One job only: scan source files for environment-variable references, compare
+them with the keys in .env.example, and report the drift:
+
+- missing: used in code, but not documented in .env.example
+- extra:   documented in .env.example, but not used in code
+
+Exit codes: 0 = in sync, 1 = drift found, 2 = usage error (argparse).
+
+With --fix, variables that are missing from .env.example are appended to it
+as ``NAME=`` (no value is ever invented). Extra variables are never removed
+automatically: deleting a documented variable is a human decision.
+
+Standard library only. Nothing is sent anywhere; everything runs locally.
+
+Supported references (text patterns, not an AST -- see README limits):
+- Python: os.environ["X"], os.environ.get("X"), os.getenv("X")
+- JavaScript/TypeScript: process.env.X, process.env["X"],
+  import.meta.env.X, import.meta.env["X"]
+- Go: os.Getenv("X")
+- PHP: getenv("X"), $_ENV["X"], $_SERVER["X"]
+- Shell: ${X}, $X
+"""
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+VAR = r"[A-Za-z_][A-Za-z0-9_]*"
+# Shell locals are lowercase by convention, so shell patterns only match
+# uppercase names -- otherwise every $count in a script would be flagged.
+SHELL_VAR = r"[A-Z_][A-Z0-9_]*"
+
+PATTERNS = [
+    # Python
+    re.compile(r"os\.environ\[\s*['\"](" + VAR + r")['\"]\s*\]"),
+    re.compile(r"os\.environ\.get\(\s*['\"](" + VAR + r")['\"]"),
+    re.compile(r"os\.getenv\(\s*['\"](" + VAR + r")['\"]"),
+    # JavaScript / TypeScript
+    re.compile(r"process\.env\.(" + VAR + r")"),
+    re.compile(r"process\.env\[\s*['\"](" + VAR + r")['\"]\s*\]"),
+    re.compile(r"import\.meta\.env\.(" + VAR + r")"),
+    re.compile(r"import\.meta\.env\[\s*['\"](" + VAR + r")['\"]\s*\]"),
+    # Go
+    re.compile(r"os\.Getenv\(\s*\"(" + VAR + r")\""),
+    # PHP
+    re.compile(r"getenv\(\s*['\"](" + VAR + r")['\"]"),
+    re.compile(r"\$_(?:ENV|SERVER)\[\s*['\"](" + VAR + r")['\"]\s*\]"),
+    # Shell: ${VAR} and $VAR (braced form first, so ${VAR} is not double-counted)
+    re.compile(r"\$\{(" + SHELL_VAR + r")"),
+    # Exclude PHP's $_ENV / $_SERVER, which have their own pattern above.
+    re.compile(r"\$(?!\{)(?!_(?:ENV|SERVER)\b)(" + SHELL_VAR + r")"),
+]
+
+EXTENSIONS = {".py", ".js", ".jsx", ".ts", ".tsx", ".sh", ".bash", ".zsh", ".go", ".php"}
+
+EXCLUDED_DIRS = {
+    ".git", "node_modules", "__pycache__", ".venv", "venv", "env",
+    "dist", "build", ".tox", ".pytest_cache", "coverage", ".idea", ".vscode",
+}
+
+ENV_FILENAMES = {".env", ".env.example", ".env.local", ".env.sample"}
+
+
+def parse_example(text):
+    """Return the set of variable names documented in .env.example text."""
+    keys = set()
+    for raw_line in text.splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if line.startswith("export "):
+            line = line[len("export "):].strip()
+        if "=" not in line:
+            continue
+        key = line.split("=", 1)[0].strip()
+        if re.fullmatch(VAR, key):
+            keys.add(key)
+    return keys
+
+
+def scan_text(text):
+    """Return the set of variable names referenced in one source file."""
+    used = set()
+    for pattern in PATTERNS:
+        used.update(pattern.findall(text))
+    return used
+
+
+def iter_source_files(root):
+    """Yield source files under root, skipping excluded dirs and env files."""
+    for path in sorted(root.rglob("*")):
+        if not path.is_file():
+            continue
+        if any(part in EXCLUDED_DIRS for part in path.relative_to(root).parts[:-1]):
+            continue
+        if path.name in ENV_FILENAMES:
+            continue
+        if path.suffix in EXTENSIONS:
+            yield path
+
+
+def scan_directory(root):
+    """Return (used_vars, files_checked) for the source tree under root."""
+    used = set()
+    files_checked = 0
+    for path in iter_source_files(root):
+        try:
+            text = path.read_text(encoding="utf-8", errors="ignore")
+        except OSError:
+            continue
+        files_checked += 1
+        used.update(scan_text(text))
+    return used, files_checked
+
+
+def check(root, example_path, ignored):
+    """Run one drift check. Returns a dict with sorted lists and a verdict."""
+    used, files_checked = scan_directory(root)
+    used -= set(ignored)
+    try:
+        documented = parse_example(example_path.read_text(encoding="utf-8"))
+    except OSError:
+        documented = set()
+    missing = sorted(used - documented)
+    extra = sorted(documented - used)
+    return {
+        "root": str(root),
+        "example": str(example_path),
+        "files_checked": files_checked,
+        "used": sorted(used),
+        "documented": sorted(documented),
+        "missing": missing,
+        "extra": extra,
+        "in_sync": not missing and not extra,
+    }
+
+
+def render_text(result):
+    """Render a drift check as human-readable text."""
+    lines = [
+        "Checked: {} file(s)".format(result["files_checked"]),
+        "Used in code: {}".format(len(result["used"])),
+        "Documented in .env.example: {}".format(len(result["documented"])),
+    ]
+    if result["missing"]:
+        lines.append("Missing from .env.example (used but not documented):")
+        lines.extend("  - {}".format(name) for name in result["missing"])
+    if result["extra"]:
+        lines.append("Extra in .env.example (documented but not used):")
+        lines.extend("  - {}".format(name) for name in result["extra"])
+    lines.append("Result: {}".format("IN SYNC" if result["in_sync"] else "DRIFT"))
+    return "\n".join(lines)
+
+
+def apply_fix(result, example_path):
+    """Append missing variables to .env.example as NAME= lines. Returns names."""
+    missing = result["missing"]
+    if not missing:
+        return []
+    with example_path.open("a", encoding="utf-8") as handle:
+        if example_path.stat().st_size > 0:
+            with example_path.open("rb") as probe:
+                probe.seek(-1, 2)
+                if probe.read(1) != b"\n":
+                    handle.write("\n")
+        handle.write("".join("{}=\n".format(name) for name in missing))
+    return missing
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(
+        prog="env-example-sync",
+        description="Report drift between code's env-var use and .env.example.",
+    )
+    parser.add_argument("path", nargs="?", default=".",
+                        help="project directory to scan (default: current directory)")
+    parser.add_argument("--example", default=".env.example",
+                        help="path to .env.example (default: .env.example)")
+    parser.add_argument("--ignore", default="",
+                        help="comma-separated variable names to ignore")
+    parser.add_argument("--format", choices=["text", "json"], default="text",
+                        help="output format (default: text)")
+    parser.add_argument("--fix", action="store_true",
+                        help="append missing variables to .env.example as NAME=")
+    args = parser.parse_args(argv)
+
+    root = Path(args.path)
+    if not root.is_dir():
+        parser.error("not a directory: {}".format(root))
+    example_path = Path(args.example)
+    ignored = [name.strip() for name in args.ignore.split(",") if name.strip()]
+
+    result = check(root, example_path, ignored)
+
+    if args.fix and result["missing"]:
+        fixed = apply_fix(result, example_path)
+        result = check(root, example_path, ignored)
+        if args.format == "text":
+            print("Added to {}: {}".format(example_path, ", ".join(fixed)))
+
+    if args.format == "json":
+        print(json.dumps(result, indent=2, sort_keys=True))
+    else:
+        print(render_text(result))
+    return 0 if result["in_sync"] else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

env_example_sync_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: env-example-sync-cli
+Version: 0.1.0
+Summary: Scan code for environment variables, compare with `.env.example`, and fail CI when they drift.
+Author: Haider Ali
+License: MIT
+Project-URL: Homepage, https://github.com/haiderstudio/env-example-sync-cli
+Project-URL: Repository, https://github.com/haiderstudio/env-example-sync-cli
+Project-URL: Issues, https://github.com/haiderstudio/env-example-sync-cli/issues
+Keywords: env,dotenv,environment-variables,cli,developer-tools
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# env-example-sync-cli
+
+Scan code for environment variables, compare with `.env.example`, and fail CI when they drift.
+
+[![CI](https://github.com/haiderstudio/env-example-sync-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/haiderstudio/env-example-sync-cli/actions/workflows/ci.yml) [![Licence: MIT](https://img.shields.io/badge/Licence-MIT-yellow.svg)](LICENSE)
+
+## What it does
+
+Every project has a moment where someone adds `os.environ["NEW_KEY"]` to code
+and forgets `.env.example`, and the next developer's setup breaks silently.
+`env-example-sync` catches that before it ships:
+
+- **Missing** — used in code, but not documented in `.env.example`.
+- **Extra** — documented in `.env.example`, but no longer used in code.
+- **Exit code 1 on drift, 0 when in sync** — so it works as a CI gate.
+- **`--fix`** appends missing variables to `.env.example` as `NAME=` — no value
+  is ever invented, and extra variables are never deleted automatically.
+
+It scans Python, JavaScript/TypeScript, Go, PHP, and shell files, and skips
+`node_modules`, `.git`, virtualenvs, and `.env*` files themselves.
+
+## What it does NOT do
+
+- It does not read, print, or upload any real secret value. It only ever
+  reports variable **names**.
+- It does not load a real `.env` file, and it never touches one.
+- It does not delete variables from `.env.example` — removing a documented
+  variable is a human decision, not an automated one.
+- It does not parse code as an AST. It matches text patterns, so a variable
+  named only in a comment still counts as used. That is deliberate: it errs
+  toward keeping a variable documented rather than deleting it.
+- Shell scripts only match uppercase names (`$HOME` counts, `$home` does not),
+  because lowercase shell words are locals by convention, not env vars.
+- It sends nothing anywhere. Everything runs locally, Python standard
+  library only.
+
+## Install
+
+No install step and no dependencies — Python 3.10+ is enough:
+
+```sh
+git clone https://github.com/haiderstudio/env-example-sync-cli.git
+cd env-example-sync-cli
+python3 src/env_example_sync.py --help
+```
+
+## Usage
+
+From your project root, where `.env.example` lives:
+
+```sh
+python3 src/env_example_sync.py .
+```
+
+Real output on the bundled sample project (see `examples/sample-project`,
+where `TIMEOUT` is used but undocumented and `OLD_VAR` is documented but
+unused):
+
+```text
+Checked: 1 file(s)
+Used in code: 3
+Documented in .env.example: 3
+Missing from .env.example (used but not documented):
+  - TIMEOUT
+Extra in .env.example (documented but not used):
+  - OLD_VAR
+Result: DRIFT
+```
+
+That run exits with code 1 — exactly what a CI gate wants.
+
+Other useful forms:
+
+```sh
+# Machine-readable output for another tool to consume
+python3 src/env_example_sync.py . --format json
+
+# Ignore variables that are set by the platform, not by the project
+python3 src/env_example_sync.py . --ignore PATH,HOME
+
+# Append only the missing variables (as NAME=), then re-check
+python3 src/env_example_sync.py . --fix
+
+# Scan a different project, with its example file elsewhere
+python3 src/env_example_sync.py /path/to/project --example /path/to/project/.env.example
+```
+
+## Examples
+
+**Example 1 — a clean project passes.** A project whose code uses `API_KEY`
+and whose `.env.example` lists exactly `API_KEY` prints `Result: IN SYNC`
+and exits 0.
+
+**Example 2 — the CI gate.** Add this to a workflow and a pull request that
+adds a new env var without documenting it fails the build until
+`.env.example` is updated (or `--fix` is run and the result committed):
+
+```yaml
+- run: python3 src/env_example_sync.py .
+```
+
+**Example 3 — the `--fix` edge case.** If a project has both a missing and
+an extra variable, `--fix` appends the missing one but the run still exits
+1, because the extra variable still needs a human decision. Nothing is
+silently deleted.
+
+## How it is tested
+
+Standard library `unittest` only — 15 tests covering example parsing,
+every language pattern, missing/extra classification, exit codes, JSON
+output, `--fix`, `--ignore`, and excluded directories:
+
+```sh
+python3 tests/test_env_example_sync.py
+```
+
+All 15 pass on the files in this repo. The README's sample output above is
+the tool's real output on `examples/sample-project`, not a mock.
+
+## Related tools (and how this one differs)
+
+Similar drift checkers exist, mostly for JavaScript projects: `dotenv-audit`
+(Node, scans JS/TS and can auto-fill `.env.example` with generated
+placeholder values) and `dotdrift` (Node, compares `.env` with
+`.env.example`). This tool is the Python-stdlib alternative: it needs no
+Node or npm, covers Python, JS/TS, Go, PHP, and shell in one pass, never
+reads a real `.env` file, and `--fix` appends empty `NAME=` lines only —
+it never invents a placeholder value that could be mistaken for a real one.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Small, focused improvements are
+welcome; never weaken the safety rules (no secret values, no automatic
+deletion, no invented values).
+
+## Licence
+
+MIT — see [LICENSE](LICENSE). This is original work, written for this repo;
+the drift-checking idea is a common developer workflow, not copied code.

env_example_sync_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+env_example_sync.py,sha256=xYK5PUjRlYUaTHETku4iAGyINSHHo5ghVKOA_ZMX0XQ,7838
+env_example_sync_cli-0.1.0.dist-info/licenses/LICENSE,sha256=mTjYlQM7htiV7thgBkBwT0woURqRpTJG1eWK1Logfl8,1067
+env_example_sync_cli-0.1.0.dist-info/METADATA,sha256=n5RPeKbDqLD9yZMcuTiWm7FGKm3bxuUWoF2UAtfRJqY,6039
+env_example_sync_cli-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+env_example_sync_cli-0.1.0.dist-info/entry_points.txt,sha256=2PlQfypLvtfKJ5aKcPos2tPxxUSkiKsn9MCcQZAB0-s,59
+env_example_sync_cli-0.1.0.dist-info/top_level.txt,sha256=31pYp35qH__w1LRsr4E8qEU7g-4nMgOzOXdi6UqHFi4,17
+env_example_sync_cli-0.1.0.dist-info/RECORD,,

env_example_sync_cli-0.1.0.dist-info/WHEEL

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

env_example_sync_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+env-example-sync = env_example_sync:main

env_example_sync_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Haider Ali
+
+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_example_sync_cli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+env_example_sync