env-auditor 0.1.0__py3-none-any.whl

env_auditor-0.1.0.dist-info/METADATA

@@ -0,0 +1,234 @@
+Metadata-Version: 2.4
+Name: env-auditor
+Version: 0.1.0
+Summary: Audit environment variable consistency across a codebase.
+Project-URL: Homepage, https://github.com/SemTiOne/env-check
+Project-URL: Issues, https://github.com/SemTiOne/env-check/issues
+License: MIT License
+        
+        Copyright (c) 2026 SemTiOne
+        
+        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.
+License-File: LICENSE
+Keywords: audit,cli,devtools,dotenv,env
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# env-check
+
+[![CI](https://github.com/SemTiOne/env-check/actions/workflows/ci.yml/badge.svg)](https://github.com/SemTiOne/env-check/actions)
+[![PyPI](https://img.shields.io/pypi/v/envcheck.svg)](https://pypi.org/project/envcheck/)
+[![Python](https://img.shields.io/pypi/pyversions/envcheck.svg)](https://pypi.org/project/envcheck/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+**Audit environment variable consistency across your codebase.** Finds vars used in code but missing from `.env.example`, stale vars nobody references anymore, and required vars with no default value — in any language.
+
+```
+$ envcheck .
+
+envcheck — environment variable audit
+──────────────────────────────────────────
+
+✗  3 undocumented variables (in code, missing from .env.example)
+   DATABASE_URL          src/db/connection.py:14
+   STRIPE_WEBHOOK_SECRET src/payments/webhook.py:8, src/payments/webhook.py:31
+   REDIS_URL             src/cache.py:22
+
+⚠  2 stale variables (in .env.example, not found in code)
+   OLD_PAYMENT_KEY
+   DEPRECATED_FEATURE_FLAG
+
+○  2 variables with no default value (empty in .env.example)
+   SECRET_KEY
+   JWT_SECRET
+
+⚡  1 dynamic reference (runtime key construction — cannot audit statically)
+   src/config/loader.py:45  →  process.env[configKey]
+
+──────────────────────────────────────────
+Result: FAIL  (exit code 1)
+```
+
+## Why
+
+Your `.env.example` is a contract. It tells new contributors what the app needs to run. Over time that contract drifts: someone adds `process.env.NEW_KEY` to the source and forgets to document it, or removes a feature but leaves the stale key rotting in `.env.example`. `envcheck` catches both automatically, in CI, before it becomes someone else's debugging session.
+
+## Installation
+
+```bash
+pip install env-auditor
+```
+
+Requires Python 3.10+. **Zero runtime dependencies** — pure stdlib.
+
+## Usage
+
+```bash
+# Audit current directory against .env.example (default)
+envcheck
+
+# Audit a specific project
+envcheck /path/to/project
+
+# Use a different env file
+envcheck --env .env.production
+
+# Multiple env files (keys merged — union)
+envcheck --env .env.example --env .env.staging
+
+# Strict mode: fail on stale vars too
+envcheck --strict
+
+# JSON output for tooling / dashboards
+envcheck --format json | jq .undocumented
+
+# Suppress specific sections
+envcheck --ignore-stale --ignore-missing
+
+# Exclude extra directories
+envcheck --exclude vendor --exclude third_party
+```
+
+## Config file
+
+Commit a `.envcheckrc` at your project root to persist settings for your whole team:
+
+```toml
+# .envcheckrc
+env_files = [".env.example", ".env.staging"]
+exclude_dirs = ["vendor", "third_party"]
+ignore_stale = false
+strict = true
+ignore_keys = ["CI", "HOME", "USER"]
+required_keys = ["DATABASE_URL", "SECRET_KEY"]
+```
+
+Or add it to `pyproject.toml` under `[tool.envcheck]`:
+
+```toml
+[tool.envcheck]
+env_files = [".env.example"]
+strict = true
+ignore_keys = ["CI"]
+```
+
+CLI flags always override config file values.
+
+## Supported languages
+
+| Language | Detected patterns |
+|---|---|
+| JavaScript / TypeScript | `process.env.VAR`, `process.env['VAR']`, `process.env["VAR"]` |
+| Python | `os.environ['VAR']`, `os.environ.get('VAR')`, `os.getenv('VAR')` |
+| Go | `os.Getenv("VAR")`, `os.LookupEnv("VAR")` |
+| Shell | `$VAR`, `${VAR}` (`.sh`, `.bash`, `.zsh` only) |
+| Docker | `ENV VAR`, `ARG VAR` in Dockerfiles |
+| Ruby | `ENV['VAR']`, `ENV["VAR"]`, `ENV.fetch('VAR')` |
+
+Dynamic references like `process.env[someVariable]` are flagged separately — they can't be statically audited.
+
+## CLI reference
+
+| Flag | Description | Default |
+|---|---|---|
+| `PATH` | Root directory to scan | `.` |
+| `--env FILE` | Env file(s) as source of truth. Repeatable. | `.env.example` |
+| `--config FILE` | Path to config file | auto-discover `.envcheckrc` |
+| `--ignore-stale` | Suppress stale variable report | off |
+| `--ignore-missing` | Suppress empty-value report | off |
+| `--format [text\|json]` | Output format | `text` |
+| `--no-color` | Disable ANSI colors | off |
+| `--exclude DIR` | Extra directories to skip. Repeatable. | — |
+| `--strict` | Exit 1 on stale vars too | off |
+| `--version` | Show version and exit | — |
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | Clean |
+| `1` | Undocumented vars found (or stale with `--strict`) |
+| `2` | Tool error — bad args, missing files, etc. |
+
+## CI integration
+
+Block deploys when env vars drift:
+
+```yaml
+# .github/workflows/deploy.yml
+jobs:
+  env-audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install envcheck
+      - run: envcheck --strict
+```
+
+Save the report as a CI artifact:
+
+```yaml
+- run: envcheck --format json > envcheck-report.json || true
+- uses: actions/upload-artifact@v4
+  with:
+    name: envcheck-report
+    path: envcheck-report.json
+```
+
+For monorepos, run per-service:
+
+```yaml
+- run: envcheck services/api --env services/api/.env.example
+- run: envcheck services/worker --env services/worker/.env.example
+```
+
+## Security
+
+- Symlinks are never followed
+- Files over 1 MB are skipped (with a warning)
+- Lines over 2000 characters are skipped (ReDoS protection)
+- `--exclude` paths are validated to be within the scan root — path traversal rejected
+- Actual `.env` values are never stored, logged, or printed — only key names
+- No network calls, no telemetry, entirely local
+
+## Development
+
+```bash
+git clone https://github.com/SemTiOne/env-check
+cd env-check
+pip install -e .
+pip install pytest pytest-cov
+pytest --cov=envcheck --cov-report=term-missing
+```
+
+## License
+
+MIT

env_auditor-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+envcheck/__init__.py,sha256=amU28sKwTeJ9cC71SmZfY9S8mTypA4-RVgl9xEBGHDU,252
+envcheck/__main__.py,sha256=0X3XA8xNObct3tCNDoo47YjUEaFypGLjeNT0tYf3OBM,105
+envcheck/cli.py,sha256=QxTC_lqhLsQE61TTbxMlmT-Q3bfm2W2xe5M8KzmWSfo,12291
+envcheck/colors.py,sha256=82ChshmdCNZG-cZT-DS8IDw9LAwfRXhklHA23uCtne0,1473
+envcheck/config.py,sha256=IMkeMQurZV0cozQcpSmmu5D80z-1TwoXJoAG5CqJzIs,8779
+envcheck/differ.py,sha256=ed7nSvIsDlWkJHTCe7Ty3uDwDNditEq838euXh1bsiU,1516
+envcheck/parser.py,sha256=-aca72m06xI3GkY1iHHaxQdF34x7B_e3lxgLulTnce4,4833
+envcheck/patterns.py,sha256=0kso6w-tNUo3Iu4c2qxh_lUaKCweMwoadebe4awkICM,4542
+envcheck/reporter.py,sha256=CvoSPet_4zVN7LDE6SpvxsvC74qX8cilw2aBSQSm3Uw,4387
+envcheck/scanner.py,sha256=zpL5vPzjuf2UZaHd3bHX3bDLgDg1cjGmOL36j9CPjQ8,7741
+env_auditor-0.1.0.dist-info/METADATA,sha256=wIFwFKv3fMLMTZuVtL1-vv1yOC7Dlscv3Zq9ay68ygY,7911
+env_auditor-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+env_auditor-0.1.0.dist-info/entry_points.txt,sha256=vnagcFF7kFxpDUaFMg41RstibftP_qS-L9ZrKWs7EUc,47
+env_auditor-0.1.0.dist-info/licenses/LICENSE,sha256=eLKOmoG52yqMSkJEKmSSj5jVl2BL_Ovcs-Mouy7v320,1065
+env_auditor-0.1.0.dist-info/RECORD,,

env_auditor-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

env_auditor-0.1.0.dist-info/entry_points.txt

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

env_auditor-0.1.0.dist-info/licenses/LICENSE

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

envcheck/__init__.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from importlib.metadata import version, PackageNotFoundError
+
+try:
+    __version__: str = version("envcheck")
+except PackageNotFoundError:  # pragma: no cover
+    __version__ = "0.0.0-dev"
+
+__all__ = ["__version__"]

envcheck/__main__.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from envcheck.cli import main
+
+if __name__ == "__main__":
+    main()

envcheck/cli.py

@@ -0,0 +1,350 @@
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from dataclasses import replace as dataclass_replace
+from pathlib import Path
+from typing import Optional
+
+from envcheck import __version__
+from envcheck.colors import supports_color
+from envcheck.config import (
+    EnvCheckConfig,
+    _dict_to_config,
+    _parse_toml_file,
+    load_config,
+    merge_cli_into_config,
+)
+from envcheck.differ import diff_keys
+from envcheck.parser import parse_env_files
+from envcheck.reporter import render_json, render_text
+from envcheck.scanner import scan_directory
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Argument parser
+# ──────────────────────────────────────────────────────────────────────────────
+
+def _build_parser() -> argparse.ArgumentParser:
+    """Build and return the CLI argument parser."""
+    parser = argparse.ArgumentParser(
+        prog="envcheck",
+        description="Audit environment variable consistency across a codebase.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        add_help=False,
+    )
+    parser.add_argument(
+        "path",
+        metavar="PATH",
+        nargs="?",
+        default=".",
+        help="Root directory to scan. Defaults to current directory.",
+    )
+    parser.add_argument(
+        "--env",
+        metavar="FILE",
+        action="append",
+        dest="env_files",
+        default=None,
+        help=(
+            "Env file(s) to treat as source of truth. "
+            "Can be specified multiple times. Default: .env.example"
+        ),
+    )
+    parser.add_argument(
+        "--ignore-stale",
+        action="store_true",
+        default=False,
+        help="Do not report stale variables.",
+    )
+    parser.add_argument(
+        "--ignore-missing",
+        action="store_true",
+        default=False,
+        help="Do not report variables with empty values.",
+    )
+    parser.add_argument(
+        "--format",
+        choices=["text", "json"],
+        default=None,
+        help="Output format. Default: text",
+    )
+    parser.add_argument(
+        "--no-color",
+        action="store_true",
+        default=False,
+        help="Disable ANSI color output.",
+    )
+    parser.add_argument(
+        "--exclude",
+        metavar="DIR",
+        action="append",
+        dest="exclude_dirs",
+        default=None,
+        help=(
+            "Additional directories to exclude from scanning. "
+            "Can be specified multiple times."
+        ),
+    )
+    parser.add_argument(
+        "--strict",
+        action="store_true",
+        default=False,
+        help="Exit 1 on stale variables too, not just undocumented ones.",
+    )
+    parser.add_argument(
+        "--config",
+        metavar="FILE",
+        default=None,
+        help="Path to config file. Default: auto-discover .envcheckrc in scan root.",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"envcheck {__version__}",
+    )
+    parser.add_argument(
+        "-h",
+        "--help",
+        action="help",
+        help="Show this message and exit.",
+    )
+    return parser
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Path validation
+# ──────────────────────────────────────────────────────────────────────────────
+
+def _resolve_scan_root(raw_path: str) -> Path:
+    """Resolve and validate the scan root directory.
+
+    Args:
+        raw_path: Raw path string from CLI argument.
+
+    Returns:
+        Resolved absolute Path.
+
+    Raises:
+        SystemExit(2): If the path does not exist or is not a directory.
+    """
+    try:
+        resolved = Path(raw_path).resolve()
+    except (OSError, ValueError) as exc:
+        _die(f"Invalid path '{raw_path}': {exc}")
+    if not resolved.exists():
+        _die(f"Path does not exist: {resolved}")
+    if not resolved.is_dir():
+        _die(f"Path is not a directory: {resolved}")
+    return resolved
+
+
+def _resolve_env_files(raw_files: list[str], scan_root: Path) -> list[Path]:
+    """Resolve and validate env file paths, warning on missing files.
+
+    Args:
+        raw_files: Raw file path strings from CLI or config.
+        scan_root: Resolved scan root used for relative path resolution.
+
+    Returns:
+        List of resolved Paths for files that exist.
+    """
+    paths: list[Path] = []
+    for raw in raw_files:
+        p = Path(raw)
+        if not p.is_absolute():
+            p = scan_root / p
+        try:
+            resolved = p.resolve()
+        except (OSError, ValueError) as exc:
+            _die(f"Invalid env file path '{raw}': {exc}")
+        if not resolved.exists():
+            print(
+                f"envcheck: warning: env file not found: {resolved}",
+                file=sys.stderr,
+            )
+            continue
+        if not resolved.is_file():
+            _die(f"Env path is not a file: {resolved}")
+        paths.append(resolved)
+    return paths
+
+
+def _resolve_exclude_dirs(raw_dirs: list[str], scan_root: Path) -> list[Path]:
+    """Resolve --exclude paths, rejecting any that escape the scan root.
+
+    Security: path traversal is rejected — each resolved path must be
+    a descendant of scan_root.
+
+    Args:
+        raw_dirs: Raw directory strings from CLI or config.
+        scan_root: Resolved absolute scan root.
+
+    Returns:
+        List of resolved absolute Paths within scan_root.
+    """
+    resolved_list: list[Path] = []
+    for raw in raw_dirs:
+        # Strip newlines to prevent any injection via crafted input
+        raw_safe = re.sub(r"[\r\n]", "", raw)
+        p = Path(raw_safe)
+        if not p.is_absolute():
+            p = scan_root / p
+        try:
+            resolved = p.resolve()
+        except (OSError, ValueError) as exc:
+            _die(f"Invalid exclude path '{raw_safe}': {exc}")
+        try:
+            resolved.relative_to(scan_root)
+        except ValueError:
+            _die(
+                f"Excluded path '{raw_safe}' resolves to '{resolved}', "
+                f"which is outside scan root '{scan_root}'. "
+                f"Path traversal rejected."
+            )
+        resolved_list.append(resolved)
+    return resolved_list
+
+
+def _die(msg: str) -> None:
+    """Print an error to stderr and exit with code 2 (tool error)."""
+    print(f"envcheck: error: {msg}", file=sys.stderr)
+    sys.exit(2)
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Config loading
+# ──────────────────────────────────────────────────────────────────────────────
+
+def _build_config(args: argparse.Namespace, scan_root: Path) -> EnvCheckConfig:
+    """Load config file and apply CLI overrides on top.
+
+    Config file is auto-discovered in scan_root unless ``--config`` is given.
+    CLI flags always win over config file values.
+
+    Args:
+        args: Parsed CLI arguments.
+        scan_root: Resolved scan root.
+
+    Returns:
+        Final merged EnvCheckConfig.
+    """
+    if args.config:
+        config_path = Path(args.config).resolve()
+        if not config_path.is_file():
+            _die(f"Config file not found: {config_path}")
+        try:
+            raw = _parse_toml_file(config_path, config_path.name == "pyproject.toml")
+            cfg = _dict_to_config(raw or {}, config_path)
+        except (OSError, ValueError, KeyError) as exc:
+            _die(f"Could not parse config file {config_path}: {exc}")
+    else:
+        cfg = load_config(scan_root)
+
+    return merge_cli_into_config(
+        cfg,
+        env_files=args.env_files,
+        exclude_dirs=args.exclude_dirs,
+        ignore_stale=args.ignore_stale or None,
+        ignore_missing=args.ignore_missing or None,
+        strict=args.strict or None,
+        format=args.format,
+    )
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Audit pipeline
+# ──────────────────────────────────────────────────────────────────────────────
+
+def _run_audit(
+    scan_root: Path,
+    cfg: EnvCheckConfig,
+    use_color: bool,
+) -> tuple[int, str]:
+    """Execute the full audit pipeline.
+
+    Args:
+        scan_root: Resolved absolute path to scan.
+        cfg: Merged configuration.
+        use_color: Whether to emit ANSI color codes in text output.
+
+    Returns:
+        ``(exit_code, rendered_output)`` tuple.
+    """
+    env_paths = _resolve_env_files(cfg.env_files, scan_root)
+    if not env_paths:
+        print(
+            "envcheck: warning: no env files found; "
+            "all code references will be reported as undocumented.",
+            file=sys.stderr,
+        )
+
+    extra_exclude: list[Path] = []
+    if cfg.exclude_dirs:
+        extra_exclude = _resolve_exclude_dirs(cfg.exclude_dirs, scan_root)
+
+    scan_result = scan_directory(scan_root, extra_exclude=extra_exclude or None)
+    parsed_env = parse_env_files(env_paths)
+    diff = diff_keys(
+        code_keys=scan_result.all_keys,
+        documented_keys=parsed_env.all_keys,
+        empty_keys=parsed_env.empty_keys,
+    )
+
+    ignore_keys: set[str] = set(cfg.ignore_keys) if cfg.ignore_keys else set()
+    fmt = cfg.format or "text"
+
+    if fmt == "json":
+        output = render_json(
+            diff,
+            scan_result,
+            ignore_stale=cfg.ignore_stale,
+            ignore_missing=cfg.ignore_missing,
+            ignore_keys=ignore_keys,
+        )
+    else:
+        output = render_text(
+            diff,
+            scan_result,
+            use_color=use_color,
+            ignore_stale=cfg.ignore_stale,
+            ignore_missing=cfg.ignore_missing,
+            ignore_keys=ignore_keys,
+        )
+
+    effective_undoc = diff.undocumented - ignore_keys
+    effective_stale = diff.stale - ignore_keys
+
+    if effective_undoc:
+        return 1, output
+    if cfg.strict and effective_stale:
+        return 1, output
+    return 0, output
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Entry point
+# ──────────────────────────────────────────────────────────────────────────────
+
+def main(argv: Optional[list[str]] = None) -> None:
+    """Parse arguments, run the audit, and exit with the appropriate code.
+
+    Exit codes:
+        0 — clean (no undocumented vars; no stale with --strict)
+        1 — undocumented variables found (or stale with --strict)
+        2 — tool error (bad arguments, unreadable config, etc.)
+    """
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    # Resolve color preference before any output.
+    # --no-color disables color without mutating os.environ.
+    use_color = (not args.no_color) and supports_color()
+
+    scan_root = _resolve_scan_root(args.path)
+    cfg = _build_config(args, scan_root)
+
+    exit_code, output = _run_audit(scan_root, cfg, use_color)
+    print(output)
+    sys.exit(exit_code)