env-example-sync-cli 0.1.0__tar.gz

env_example_sync_cli-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,139 @@
+# 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/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "env-example-sync-cli"
+version = "0.1.0"
+description = "Scan code for environment variables, compare with `.env.example`, and fail CI when they drift."
+readme = { file = "README.md", content-type = "text/markdown" }
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Haider Ali" }]
+keywords = ["env", "dotenv", "environment-variables", "cli", "developer-tools"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development",
+]
+urls = { Homepage = "https://github.com/haiderstudio/env-example-sync-cli", Repository = "https://github.com/haiderstudio/env-example-sync-cli", Issues = "https://github.com/haiderstudio/env-example-sync-cli/issues" }
+
+[project.scripts]
+env-example-sync = "env_example_sync:main"
+
+[tool.setuptools.package-dir]
+"" = "src"
+
+[tool.setuptools]
+py-modules = ["env_example_sync"]

env_example_sync_cli-0.1.0/setup.cfg

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

env_example_sync_cli-0.1.0/src/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/src/env_example_sync_cli.egg-info/PKG-INFO

@@ -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/src/env_example_sync_cli.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+LICENSE
+README.md
+pyproject.toml
+src/env_example_sync.py
+src/env_example_sync_cli.egg-info/PKG-INFO
+src/env_example_sync_cli.egg-info/SOURCES.txt
+src/env_example_sync_cli.egg-info/dependency_links.txt
+src/env_example_sync_cli.egg-info/entry_points.txt
+src/env_example_sync_cli.egg-info/top_level.txt
+tests/test_env_example_sync.py

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

@@ -0,0 +1 @@
+

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

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

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

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

env_example_sync_cli-0.1.0/tests/test_env_example_sync.py

@@ -0,0 +1,186 @@
+#!/usr/bin/env python3
+"""Tests for env_example_sync. Standard library only; run with:
+
+    python3 tests/test_env_example_sync.py
+"""
+
+import json
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+
+from env_example_sync import check, parse_example, scan_text  # noqa: E402
+
+
+def write(path, text):
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(text, encoding="utf-8")
+    return path
+
+
+class TestParseExample(unittest.TestCase):
+    def test_comments_export_and_values_with_equals(self):
+        text = (
+            "# comment\n"
+            "\n"
+            "export API_KEY=abc\n"
+            "DATABASE_URL=postgres://host/db?x=1\n"
+            "EMPTY=\n"
+            "not a pair\n"
+        )
+        self.assertEqual(
+            parse_example(text), {"API_KEY", "DATABASE_URL", "EMPTY"})
+
+    def test_empty_example(self):
+        self.assertEqual(parse_example(""), set())
+
+
+class TestScanText(unittest.TestCase):
+    def test_python_patterns(self):
+        text = (
+            "a = os.environ['API_KEY']\n"
+            'b = os.environ.get("DATABASE_URL")\n'
+            "c = os.getenv('TIMEOUT')\n"
+        )
+        self.assertEqual(
+            scan_text(text), {"API_KEY", "DATABASE_URL", "TIMEOUT"})
+
+    def test_js_ts_patterns(self):
+        text = (
+            "const k = process.env.STRIPE_KEY;\n"
+            "const s = process.env['SENTRY_DSN'];\n"
+            "const v = import.meta.env.VITE_API_URL;\n"
+        )
+        self.assertEqual(
+            scan_text(text), {"STRIPE_KEY", "SENTRY_DSN", "VITE_API_URL"})
+
+    def test_shell_and_go_and_php_patterns(self):
+        text = (
+            'd = os.Getenv("GO_KEY")\n'
+            "e = getenv('PHP_KEY');\n"
+            "f = $_ENV['SERVER_KEY'];\n"
+            "echo ${SHELL_KEY} and $PLAIN_KEY\n"
+        )
+        self.assertEqual(
+            scan_text(text),
+            {"GO_KEY", "PHP_KEY", "SERVER_KEY", "SHELL_KEY", "PLAIN_KEY"})
+
+    def test_lowercase_shell_words_are_not_variables(self):
+        # Shell locals are lowercase by convention, so $home is a local
+        # variable, not an environment variable, and is not flagged.
+        self.assertEqual(scan_text("echo $home\n"), set())
+
+
+class TestCheck(unittest.TestCase):
+    def test_missing_and_extra(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            write(root / "app.py",
+                  "import os\nk = os.environ['API_KEY']\n")
+            example = write(root / ".env.example",
+                            "API_KEY=\nOLD_VAR=\n")
+            result = check(root, example, [])
+            self.assertEqual(result["missing"], [])
+            self.assertEqual(result["extra"], ["OLD_VAR"])
+            self.assertFalse(result["in_sync"])
+
+    def test_in_sync(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            write(root / "app.py",
+                  "import os\nk = os.environ['API_KEY']\n")
+            example = write(root / ".env.example", "API_KEY=\n")
+            self.assertTrue(check(root, example, [])["in_sync"])
+
+    def test_missing_example_file_means_all_used_are_missing(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            write(root / "app.py",
+                  "import os\nk = os.environ['API_KEY']\n")
+            result = check(root, root / ".env.example", [])
+            self.assertEqual(result["missing"], ["API_KEY"])
+
+    def test_ignore_list(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            write(root / "app.py",
+                  "import os\nk = os.environ['API_KEY']\n")
+            example = write(root / ".env.example", "")
+            self.assertTrue(check(root, example, ["API_KEY"])["in_sync"])
+
+    def test_excluded_dirs_are_not_scanned(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            write(root / "node_modules" / "pkg" / "index.js",
+                  "const x = process.env.HIDDEN_KEY;\n")
+            write(root / "app.py", "import os\nk = os.environ['API_KEY']\n")
+            example = write(root / ".env.example", "API_KEY=\n")
+            result = check(root, example, [])
+            self.assertEqual(result["used"], ["API_KEY"])
+            self.assertEqual(result["files_checked"], 1)
+
+    def test_env_files_are_not_scanned_as_code(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            write(root / ".env", "SECRET_IN_ENV_FILE=1\n")
+            write(root / "app.py", "print('nothing')\n")
+            example = write(root / ".env.example", "")
+            result = check(root, example, [])
+            self.assertEqual(result["used"], [])
+
+
+class TestCli(unittest.TestCase):
+    def run_tool(self, *args, cwd):
+        tool = Path(__file__).resolve().parents[1] / "src" / "env_example_sync.py"
+        return subprocess.run(
+            [sys.executable, str(tool), *args],
+            cwd=cwd, capture_output=True, text=True, check=False)
+
+    def test_drift_exits_1_and_sync_exits_0(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            write(root / "app.py",
+                  "import os\nk = os.environ['API_KEY']\n")
+            write(root / ".env.example", "API_KEY=\nOLD_VAR=\n")
+            drift = self.run_tool(".", cwd=tmp)
+            self.assertEqual(drift.returncode, 1)
+            self.assertIn("OLD_VAR", drift.stdout)
+            write(root / ".env.example", "API_KEY=\n")
+            sync = self.run_tool(".", cwd=tmp)
+            self.assertEqual(sync.returncode, 0)
+            self.assertIn("IN SYNC", sync.stdout)
+
+    def test_json_output(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            write(root / "app.py",
+                  "import os\nk = os.environ['API_KEY']\n")
+            write(root / ".env.example", "")
+            proc = self.run_tool(".", "--format", "json", cwd=tmp)
+            data = json.loads(proc.stdout)
+            self.assertEqual(data["missing"], ["API_KEY"])
+            self.assertFalse(data["in_sync"])
+
+    def test_fix_appends_missing_only(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            write(root / "app.py",
+                  "import os\nk = os.environ['API_KEY']\n"
+                  "j = os.environ['SECOND_KEY']\n")
+            write(root / ".env.example", "API_KEY=\nOLD_VAR=\n")
+            proc = self.run_tool(".", "--fix", cwd=tmp)
+            # OLD_VAR is still extra, so drift remains -- but SECOND_KEY
+            # must now be documented, and API_KEY must not be duplicated.
+            self.assertEqual(proc.returncode, 1)
+            content = (root / ".env.example").read_text(encoding="utf-8")
+            self.assertEqual(content.count("API_KEY="), 1)
+            self.assertIn("SECOND_KEY=\n", content)
+            self.assertIn("OLD_VAR=\n", content)
+
+
+if __name__ == "__main__":
+    unittest.main()